<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
-->

<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Lazyload Images</title>
    <link rel="stylesheet" href="doc.css">
  </head>
  <body>
<!--#include virtual="_header.html" -->


  <div id=content>
<h1>Lazyload Images</h1>
<h2>Configuration</h2>
<p>
The 'Lazyload Images' filter is enabled by specifying
<dl>
  <dt>Apache:<dd><pre class="prettyprint"
     >ModPagespeedEnableFilters lazyload_images</pre>
  <dt>Nginx:<dd><pre class="prettyprint"
     >pagespeed EnableFilters lazyload_images;</pre>
</dl>
in the configuration file.

<h2>Objective</h2>
<p>
Optimize browser rendering and reduce number of HTTP round-trips by deferring
the loading of images which are not in the client's viewport.  This filter
implements the PageSpeed rules for <a
  target="_blank" href="https://developers.google.com/speed/docs/best-practices/rendering" target="_blank">optimizing browser
  rendering</a> and <a target="_blank" href="https://developers.google.com/speed/docs/best-practices/rtt" target="_blank">minimizing round
  trip times</a>.
</a>
</p>

<h2>Description</h2>
<p>
The lazyload_images filter defers loading of images until they
become visible in the client's viewport or the page's <code>onload</code>
event fires. This avoids blocking the download of other critical resources
necessary for rendering the above the fold section of the page.
</p>
<p>
The filter changes the <code>src</code> attributes of <code>&lt;img&gt;</code>
elements on each HTML page to <code>data-pagespeed-lazy-src</code>. It attaches
an <code>onload</code> handler to these elements to determine whether the
element is in the client's viewport, and if so, loads it. It also attaches an
<code>onscroll</code> handler to the page, so that elements below the fold
are loaded when they become visible in the client's viewport as the user
scrolls down the page.
</p>


<h2 id="lazyload-after-onload">Lazyload After Onload</h2>
<p>
Additionally, in 1.8.31.2 and later, all images on the page that haven't yet
been loaded will be forcefully loaded after the page's <code>onload</code> event
is fired. This reduces jank when scrolling the page, especially on mobile
devices, at the cost of downloading bytes for images that may never be displayed
to the user.
</p>
<p>
To disable loading of images on page <code>onload</code>, set:</p>
<dl>
  <dt>Apache:<dd><pre class="prettyprint"
     >ModPagespeedLazyloadImagesAfterOnload off</pre>
  <dt>Nginx:<dd><pre class="prettyprint"
     >pagespeed LazyloadImagesAfterOnload off;</pre>
</dl>

<h2 id="lazyload-blank-url">Blank Url</h2>
<p>
By default, when the page is initially viewed, a 1x1 blank image is served from
<a href="configuration#pagespeed_static">pagespeed_static</a>.  It is also
possible to use the same image served by Google's network, or any image that you
choose, by specifying:</p>
<dl>
  <dt>Apache:<dd><pre class="prettyprint"
     >ModPagespeedLazyloadImagesBlankUrl "https://www.gstatic.com/psa/static/1.gif"</pre>
  <dt>Nginx:<dd><pre class="prettyprint"
     >pagespeed LazyloadImagesBlankUrl "https://www.gstatic.com/psa/static/1.gif";</pre>
</dl>
<p>An advantage of this approach is that this gif may already be in
the browser cache since any PageSpeed-enabled site can share it.
However, this would send traffic to Google with your page as the
Referer.
</p>

<p>
  These directives can be used in
  <a href="configuration#htaccess">location-specific configuration
  sections</a>.
</p>

<h2 id="pagespeed_no_defer">Disabling Lazyloading Per-image</h2>
<p>
lazyload_images doesn't defer an <code>img</code> tag if it has
the <code>data-pagespeed-no-defer</code> attribute (preferred) or <code>pagespeed_no_defer</code>
attribute (deprecated).  Usage:
<pre class="prettyprint">
&lt;img data-pagespeed-no-defer src=.../&gt;
</pre>
</p>

<h2 id="ua-blacklist">User-Agent Blacklist</h2>
<p>
To ensure images are only lazyloaded in supported browsers, lazyload_images
uses a User Agent blacklist.  Browsers that will not see images loaded lazily
are:
<ul>
  <li>BlackBerry 5.0 and older</li>
  <li>The Google
    Plus <a href="https://developers.google.com/+/web/snippet/">thumbnail
    fetcher</a></li>
  <li>Web Spiders
    (<a href="https://github.com/apache/incubator-pagespeed-mod/blob/master/pagespeed/kernel/http/bot_checker.gperf">full
    list</a>)</li>
</ul>
</p>

<h2 id="beacons">Lazily loading only images below the fold</h2>
<p>
By default lazyload_images injects JavaScript that uses
a <a href="faq#beacons">beacon</a> to report back to the server the images that
are visible in the client's initial viewport (<em>above the fold</em>).
It takes a few accesses of a page for the data to be reported back and
processed but eventually the above-the-fold images will be known and will be
loaded immediately while all the other below-the-fold images will be lazily
loaded; until then all images are lazily loaded.
</p>
<p>
The use of beacons can be disabled using the
<a href="config_filters#beacons">ModPagespeedCriticalImagesBeaconEnabled</a>
directive. If they are disabled, lazyload_images will not inject the
JavaScript and will revert to lazily loading all images.
</p>

<h2>Example</h2>
<p>
The effect of this filter can be observed by comparing the
number of requests <a
  href="https://www.modpagespeed.com/examples/lazyload_images.html?ModPagespeed=off">
  before</a>
and <a
  href="https://www.modpagespeed.com/examples/lazyload_images.html?ModPagespeed=on&ModPagespeedFilters=lazyload_images">
  after</a> rewriting.
As you scroll down, you will notice that images below the fold are only
requested after they become visible in the viewport.
</p>

<h2>Risks</h2>
<p>
The computation of each image's position in the viewport may consume
additional CPU cycles on the client side.  Sites that employ
JavaScript libraries to implement lazy-loading may not work properly
with this mechanism.</p>

</div>
  <!--#include virtual="_footer.html" -->
  </body>
</html>

